home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -screenplay- / shareware / amigapmars / redcode.ref < prev    next >
Text File  |  1995-07-30  |  12KB  |  356 lines
  1.                             REDCODE REFERENCE
  2.  
  3. Simulator: pMARS
  4. Version: 0.8.0
  5. Standard: ICWS'94 draft (extended)
  6.  
  7. Language elements not currently in the draft are labeled with *, those
  8. added in this version of pMARS are labeled with +.
  9.  
  10. ________________________________________
  11. Opcodes:
  12.  
  13.     DAT     terminate process
  14.     MOV     move from A to B
  15.     ADD     add A to B, store result in B
  16.     SUB     subtract A from B, store result in B
  17.     MUL     multiply A by B, store result in B
  18.     DIV     divide B by A, store result in B if A <> 0, else terminate
  19.     MOD     divide B by A, store remainder in B if A <> 0, else terminate
  20.     JMP     transfer execution to A
  21.     JMZ     transfer execution to A if B is zero
  22.     JMN     transfer execution to A if B is non-zero
  23.     DJN     decrement B, if B is non-zero, transfer execution to A
  24.     SPL     split off process to A
  25.     SLT     skip next instruction if A is less than B
  26.     CMP     same as SEQ
  27.     SEQ     (*) Skip next instruction if A is equal to B
  28.     SNE     (*) Skip next instruction if A is not equal to B
  29.     NOP     (*) No operation
  30.     LDP     (+) Load P-space cell A into core address B
  31.     STP     (+) Store A-number into P-space cell B
  32.  
  33. ________________________________________
  34. Pseudo opcodes:
  35.  
  36.     [labels] EQU text            replaces [labels] by text
  37.             [EQU text]           (*) multi-line EQU: text continues
  38.  
  39.              ORG start           specifies execution start
  40.  
  41.              END [start]         end of assembly (optional execution start)
  42.  
  43.     [count]  FOR expression      (*) repeat enclosed instructions "expression"
  44.              ROF                 times, counter is incremented starting with 01
  45.  
  46.              PIN number          (+) P-space identification number, warriors
  47.                                  with same number share P-space
  48.  
  49. ________________________________________
  50. Modifiers:
  51.  
  52.     .A   Instructions read and write A-fields.
  53.  
  54.     .B   Instructions read and write B-fields.
  55.  
  56.     .AB  Instructions read the A-field of the A-instruction  and
  57.          the B-field of the B-instruction and write to B-fields.
  58.  
  59.     .BA  Instructions read the B-field of the A-instruction  and
  60.          the A-field of the B-instruction and write to A-fields.
  61.  
  62.     .F   Instructions read both A- and B-fields of  the  the  A-
  63.          and  B-instruction and write to both A- and B-fields (A
  64.          to A and B to B).
  65.  
  66.     .X   Instructions read both A- and B-fields of  the  the  A-
  67.          and  B-instruction  and  write  to both A- and B-fields
  68.          exchanging fields (A to B and B to A).
  69.  
  70.     .I   Instructions read and write entire instructions.
  71.  
  72. ________________________________________
  73. Addressing modes:
  74.  
  75.     #       immediate
  76.     $       direct
  77.     @       indirect using B-field
  78.     <       predecrement indirect using B-field
  79.     >       postincrement indirect using B-field
  80.     *       (*) indirect using A-field
  81.     {       (*) predecrement indirect using A-field
  82.     }       (*) postincrement indirect using A-field
  83.  
  84. ________________________________________
  85. Directives:
  86.  
  87.     ;redcode                code follows, preceding text is ignored
  88.     ;name                   name of warrior follows
  89.     ;author                 name of author follows 
  90.     ;assert                 (*) expression that must evaluate to true
  91.     ;trace [off]            (*) toggle trace bit for following instructions
  92.     ;break                  (*) set trace bit for next instruction
  93.     ;debug [static|off]     (*) enable/disable setting [static] trace bits
  94.  
  95. ________________________________________
  96. Predefined variables (*):
  97.  
  98.     CORESIZE          value of -s parameter (default: 8000)
  99.     MAXPROCESSES      value of -p parameter (default: 8000)
  100.     MAXCYCLES         value of -c parameter (default: 80000)
  101.     MAXLENGTH         value of -l parameter (default: 100)
  102.     MINDISTANCE       value of -d parameter (default: 100)
  103.     ROUNDS            (+) value of -r parameter (default: 1)
  104.     PSPACESIZE        (+) value of -S parameter (default: 1/16th CORESIZE)
  105.     CURLINE           current line in generated assembly (starts with 0)
  106.     VERSION           pMARS version ("60" is v0.6.0)
  107.     WARRIORS          number of warriors specified on command line
  108.  
  109. ________________________________________
  110. Expression operators:
  111.  
  112.     Arithmetic:
  113.         +   addition or unary plus
  114.         -   subtraction or unary minus
  115.         /   division
  116.         %   modulo (remainder of division)
  117.  
  118.     Comparison (*):
  119.         ==  equality
  120.         !=  inequality
  121.         <   less than
  122.         >   greater than
  123.         <=  less than or equal
  124.         >=  greater than or equal
  125.  
  126.     Logical (*):
  127.         &&  and
  128.         ||  or
  129.         !   unary negation
  130.  
  131.     Assignment (*):
  132.     =   (to register variables a..z)
  133.  
  134.     Comparison and logical operators return 1 for true and 0 for false.
  135.     Parentheses can be used to override this precedence order:
  136.  
  137.     1) ! - + (unary)
  138.     2) * / %
  139.     3) - + (binary)
  140.     4) == != < > <= >=
  141.     5) &&
  142.     6) ||
  143.     7) =
  144.  
  145. ________________________________________
  146. Redcode grammar:
  147.  
  148. statement_list :: statement statement_list | e ;
  149. statement :: normal_stmt<1> |
  150.              equ_stmt       |
  151.              forrof_stmt    |
  152.              comment_stmt   |
  153.              substitution_stmt<2> ;
  154.  
  155. num       :: [0-9] ;
  156. number    :: num number | num ;
  157. alpha     :: [a-zA-Z] | "_" ;
  158. alphanum  :: alpha | num ;
  159. alphanums :: alphanum alphanums | e ;
  160.  
  161. label  :: alpha alphanums ;
  162. label1 :: label label1 | label ;
  163. labels :: label1 "\n" labels | label1 ;
  164. stringization :: stringization"&"label | label ;
  165.  
  166. this_string :: (^\n)* ;
  167. comment     :: ";" this_string "\n" | e ;
  168.  
  169. equ_stmt    :: labels equ_strings ;
  170. equ_string  :: "equ" this_string comment "\n" ;
  171. equ_strings :: equ_string "\n" equ_strings | equ_string ;
  172.  
  173. forrof_stmt :: labels index "for" expression<3> comment "\n"
  174.                statement_list
  175.                "rof" this_string "\n" ;
  176. index       :: label
  177.  
  178. comment_stmt  :: info_comment | debug_comment | ignore ;
  179. ignore        :: ";" this_string "\n" ;
  180. info_comment  :: ";redcode" this_string "\n" |
  181.                  ";" "name" this_string "\n" |
  182.                  ";" "author" this_string "\n" |
  183.                  ";" "date" this_string "\n" |
  184.                  ";" "version" this_string "\n" |
  185.                  ";" "assert" expression<4> "\n" ;
  186. debug_comment :: ";" debug "\n" | ";" trace "\n" | ";" break "\n" ;
  187. debug         :: "debug" | "debug" "off" | "debug" "static" ;
  188. trace         :: "trace" | "trace" "off" ;
  189. break         :: "break" ;
  190.  
  191. Note:
  192. ----
  193. 1. Normal statements are statements in the following form:
  194.    opcode [address mode] operand [, [address mode] operand] [comment]
  195.    More details about the grammar are given in the '88 or '94 proposal.
  196.  
  197. 2. Substitution statements are labels that have been declared by EQU.
  198.    If a label is declared this way: "IMP_instr equ imp mov imp, imp + 
  199.    1", the label name IMP_instr can be thought of as a statement.  
  200.    Therefore, whenf IMP_instr is used after its declaration, it will 
  201.    be replaced by "imp mov imp, imp + 1". It has effect of declaring 
  202.    a label 'imp' and inserting the statement 'mov imp, imp + 1'.
  203.  
  204. 3. Valid expression for "FOR" statement is very close to C expression in
  205.    which operator '()' has the highest precedence, followed by 'unary +,
  206.    unary -', '*, / and %', 'binary + and binary -', '<, <=, >, >=',
  207.    '==, !=', '&&', '||', and the lowest '='.
  208.    Beside numbers, it can also has labels as its terms. All of its labels
  209.    have to be declared before "FOR" statement is invoked.
  210. 4. Valid expression for "ASSERT" statement is the same as that for "FOR".
  211.  
  212. Case sensitivity
  213. ----------------
  214.  
  215. Opcode and pseudo-opcode names are case insensitive; labels are case
  216. sensitive.
  217.  
  218. Label declaration
  219. -----------------
  220. Labels are declared in three ways:
  221.  o Using EQU. When a label name that first appears (has not been declared)
  222.    is declared with EQU, all subsequent occurences of that label name
  223.    will be replaced by the strings following the EQU.
  224.  
  225.    The following equates label THIS with "num + 1". THIS equ num + 1.
  226.  
  227.    If the string substituting the label contains other labels, those labels
  228.    are also replaced by their substituting string. Recursive reference of
  229.    labels are flagged as error.
  230.  
  231.    More than one statement can be declared as a label name. To achieve this,
  232.    declare a blank label with EQU following the statement that declares
  233.    as part of equation of a named EQU label. Thus, the declaration of the
  234.    following:
  235.    core_clear equ spl 0
  236.               equ mov 2, <-1
  237.               equ jmp -1
  238.    causes three statements are declared as strings of label core_clear.
  239.  
  240.  o As an offset relative to the current normal statement. If some labels 
  241.    appear just before any '88 or '94 opcodes, they are automatically 
  242.    declared as constants that are relative to the current statement.
  243.    For example:
  244.    first spl first                0000 spl 0
  245.    imp   mov imp, imp + 1  -----> 0001 mov 0, 1
  246.  
  247.  o As an index belonging to FOR statement. Unlike other statements, labels
  248.    declared with FOR consist of two ingredients: the last label serving
  249.    as FOR index and the remaining labels serving as the same offset pointing
  250.    at the first of the FOR statement. This allows the implementation of
  251.    base[index] kind.
  252.  
  253.    This declaration:
  254.    base
  255.    index for 3
  256.          mov base, base + index - 1
  257.          rof
  258.  
  259.    translates into:
  260.    0000 mov 0, 0
  261.    0001 mov 0, 1
  262.    0002 mov 0, 2
  263.  
  264. Stringization and declaration inside FOR/ROF:
  265. --------------------------------------------
  266.  
  267. FOR 5
  268. imp mov imp, imp + 5
  269. ROF
  270.  
  271. Declaration of the above example causes the assembler to complain for
  272. duplicating declarations. pMARS however offers the stringization feature
  273. to accomplish the same goal. Its syntax is: label"&"label"&"...
  274. The first label can be any valid alphanums and it goes untranslated.
  275. The rest of the labels have to be a FOR index and it is to be substituted
  276. accordingly. Thus:
  277.  
  278. N FOR 5
  279.   imp&N mov imp&N, imp&N + 1
  280.   ROF
  281.  
  282. are expanded into:
  283. imp01 mov imp01, imp01 + 5
  284. imp02 mov imp02, imp02 + 5
  285. imp03 mov imp03, imp03 + 5
  286. imp04 mov imp04, imp04 + 5
  287. imp05 mov imp05, imp05 + 5
  288.  
  289. It is then correctly compiled.
  290.  
  291. The following form is also valid:
  292.  
  293. prime01 equ 2
  294. prime02 equ 3
  295. prime03 equ 5
  296. prime04 equ 7
  297. prime05 equ 11
  298.  
  299. N FOR 5
  300.   dat prime&N
  301.   ROF
  302.  
  303. The conjunction of FOR statements and EQU statements:
  304. ----------------------------------------------------
  305.  
  306. If labels that are not stringized are declared inside FOR/ROF statements,
  307. the result is duplicating declaration. Although in the future it might be
  308. allowed, it is well-advised that such labels are to be declared outside of
  309. the FOR/ROF block.
  310.  
  311. If FOR statements are declared as strings of a label name using EQU such as:
  312. THIS EQU N FOR 3
  313.      EQU   mov 0, 3
  314.      EQU   ROF
  315.  
  316. The expansion of such is feasible providing that both the FOR and ROF are
  317. present in the same label name.
  318.  
  319. Therefore, the following will not work:
  320. THIS EQU N FOR 3
  321. THAT EQU   ROF
  322.  
  323. THIS
  324.  mov 0, 3
  325. THAT
  326.  
  327. or
  328.  
  329. TEST EQU N FOR 3
  330.  mov 0, 3
  331.  ROF
  332.  
  333. PMARS parsing background
  334. ------------------------
  335. Parsing is done in three steps:
  336. 1. Reading from input
  337. 2. First pass assembly
  338. 3. Second pass assembly
  339.  
  340. - During reading: info_comment is parsed, comments to be ignored are removed,
  341.   the remaining are copied into memory. If the first ';redcode' appears,
  342.   all the current contents are erased from memory. Reading is continued
  343.   until it encounters the next ';redcode'. Reading always stops when it
  344.   encounters a line containing a word END or end-of-file.
  345. - During the first pass, all labels are collected. All expansions and
  346.   removals are done in this pass. All labels before opcode are substituted
  347.   if they have been declared or declared otherwise. All labels after opcode
  348.   are preserved for the second pass. This allows forward declaration
  349.   mechanism for labels after opcode.
  350. - During the second pass, no labels are declared and collected. There is
  351.   no further statement expansions and removals. All labels that have not
  352.   been substituted are substituted. Syntax checking to meet with '88 or '94
  353.   requirement is done in this stage.
  354.  
  355. $Id: redcode.ref,v 1.5 1995/07/30 18:47:11 stst Exp stst $
  356.